home *** CD-ROM | disk | FTP | other *** search
/ NeXT Education Software Sampler 1992 Fall / NeXT Education Software Sampler 1992 Fall.iso / Programming / Classes / XText / README.txt < prev    next >
Encoding:
Text File  |  1992-05-12  |  9.4 KB  |  227 lines
  1. XText: An Extensible Text Object
  2.  
  3. This package defines a subclass of the Appkit's Text object that is
  4. designed to allow the easy addition of new key bindings, both by
  5. application programmers and end users.  It also provides a reasonably
  6. comprehensive set of initial key bindings, based largely on those of
  7. emacs.
  8.  
  9. What it looks like to the end user
  10. ----------------------------------
  11. Here's a scenario of the functionality XText could provide to the user
  12. of a hypothetical mail-reading program.
  13.  
  14. First, the user can specify custom key bindings that will be available
  15. in all programs based on XText.  For example, if you wanted
  16. ctrl-shift-K to delete to the beginning of the current line, and alt-:
  17. to add a `:' and new line after the next word, you could say
  18.  
  19.     dwrite -g KeyBindings "c'K=lineBegin:1; a':={moveWord:1 mode:0;
  20.                                                     replaceSel:\":\n\"}"
  21.  
  22. Of course, if you want key bindings that are specific to a particular
  23. application you can replace the `-g' with the name of the application.
  24. (Read the man page for dwrite if you're unfamiliar with it.)
  25.  
  26. If you would rather define all your own key bindings from scratch,
  27. rather than starting with the emacs base set, you can say
  28.  
  29.     dwrite -g KeyBase none
  30.  
  31. Second, the mail program might define its own subclasses of XText with
  32. methods on them specialized to the particular requirements of a mail
  33. program, and use XText to assign appropriate bindings to each.  For
  34. example, it might define one subclass for the message display window,
  35. and bind `n' and `p' to move to the next and previous messages.
  36. (Since this XText object is read-only, it will already have space and
  37. delete bound to forward and backward page scrolling.)
  38.  
  39. Finally, the user can specify additional bindings specific to each of
  40. these window types, that invoke their specialized methods.  For
  41. example, to bind ctrl-c to the sendMessage method, you could just say
  42.  
  43.     dwrite Mail SendWindowBindings "c'c=sendMessage"
  44.  
  45. What it looks like to the application programmer
  46. ------------------------------------------------
  47. There are a few steps required by the application programmer to use
  48. XText in this scenario.
  49.  
  50. First, occurrences of [Text alloc] must be replaced with [XText
  51. alloc].  If you're using IB to construct your Text objects it
  52. currently provides no clean way to make a ScrollView containing
  53. something other than a Text, so there is a support class XTScroller
  54. that provides just that -- simply replace your ScrollViews with
  55. XTScroller custom views and the XTexts will be constructed
  56. automatically.  (This could probably also have been handled by a
  57. custom palette, but I haven't tried to figure those out yet).  These
  58. newly-created XText objects will behave just like Text objects; in
  59. particular, they will have no key bindings yet.
  60.  
  61. Second, you need to construct a "dispatch action" to store the key
  62. bindings in; the code will look something like this:
  63.  
  64.     id action = [[XTDispatchAction alloc]
  65.                     initBase:NXGetDefaultValue("myApp","KeyBase")
  66.                     estream:nil];
  67.  
  68. The second argument to initBase:estream: is an object of class
  69. ErrorStream; this allows you to control the reporting of errors, but
  70. the default error stream (which just pops up an alert panel with the
  71. message) is usually adequate.
  72.  
  73. Third, you want to add in the user's custom key bindings:
  74.  
  75.     [action addBindings:NXGetDefaultValue("myApp","KeyBindings")
  76.             estream:nil];
  77.  
  78. To have special bindings for some XTexts (like the message window),
  79. copy this action and add them in:
  80.  
  81.     id msgAction = [[action copy]
  82.                         addBindings:"n=changeMsg:1; p=changeMsg:-1"
  83.                         estream:nil];
  84.  
  85. (This assumes you've defined a subclass of XText with a changeMsg:
  86. method.)  Then add in any custom user bindings for message windows:
  87.  
  88.     [msgaction addBindings:NXGetDefaultValue("myApp","MsgWindowBindings")
  89.                estream:nil];
  90.  
  91. Finally, attach these actions to the appropriate XText objects (each
  92. action can be shared by many XTexts):
  93.  
  94.     [simple_XText setInitialAction:action];
  95.     [msg_XText setInitialAction:msgAction];
  96.  
  97. ... and you're done.
  98.  
  99. One more thing: if you've got windows with TextFields, you probably
  100. want the key bindings to work in them too.  To arrange this you'll
  101. have to provide a delegate for your window, with a
  102. windowWillReturnFieldEditor:toObject: method that looks like this:
  103.  
  104.     - windowWillReturnFieldEditor:sender toObject:client
  105.     {
  106.         return [XText newFieldEditorFor:sender
  107.                   initialAction:action
  108.                   estream:nil];
  109.     }
  110.  
  111. The Format of Binding Specifications
  112. ------------------------------------
  113. The format used to specify bindings is:
  114.     A binding spec is a sequence of zero or more bindings,
  115.         separated by `;'s
  116.     A binding is a key spec, followed by an `=', followed by an action
  117.     A key spec is a sequence of one or more key combinations,
  118.         separated by `,'s
  119.     A key combination is a sequence of zero or more modifiers,
  120.         followed by a key
  121.     A modifier is `c' (control), `s' (shift), `a' (alt), or `m' (command)
  122.     A key is a `'' followed by any character (designates the key that
  123.         generates that character), or a 2-digit hex key code, as documented
  124.         in /NextLibrary/Documentation/NextDev/Summaries/06_KeyInfo
  125.     An action is a message, or a sequence of actions separated by `;'s
  126.         and enclosed in `{}'s
  127.     A message is something like `moveWord:-1 mode:1' or
  128.         `replaceSel: "hi there\n"' (at most two arguments, which must
  129.         be either integers or strings)
  130.  
  131. Some examples:
  132.  
  133.     c'w, a'h = moveWord:-1 mode:1
  134.     c'b=moveChar:-1 mode:0; c'B=moveChar:-1 mode:3
  135.  
  136. (c'B could also have been written as cs'b, or as cs35).
  137.  
  138.     csam49={docBegin:0; moveWord:5 mode:2; docEnd:0; paste:0}
  139.  
  140. (makes ctrl-shift-alt-command-escape move the first five words to the
  141. end of the document!)
  142.  
  143. A Simple Testbed
  144. ----------------
  145. This distribution also includes a very simple demonstration program,
  146. called XTDemo.  XTDemo puts up a single window with an XText to play
  147. with, and an XText-backed text field in which you can enter new key
  148. bindings.
  149.  
  150. In addition, XTDemo adds a custom key binding so that ctrl-shift-Q
  151. inserts the key code for the next key you hit; for example,
  152. ctrl-shift-Q ctrl-alt-escape inserts the string `ca49'.
  153.  
  154. The Emacs base set
  155. ------------------
  156. The key bindings provided in the default base set are:
  157.  
  158.     Movement
  159.         ctrl-f, ctrl-b              move one character forward / back
  160.         alt-f, alt-b                move one word forward / back
  161.         ctrl-n, ctrl-p              move one line down / up
  162.         ctrl-a, ctrl-e              move to beginning / end of line
  163.         alt-<, alt->                move to beginning / end of document
  164.  
  165.     Deletion
  166.         ctrl-d, del (or ctrl-h)     delete next / previous character
  167.         alt-d, alt-del (or alt-h)   delete next / previous word
  168.         ctrl-k                      delete to end of line
  169.  
  170.     Selection
  171.         ctrl-shift-F, ctrl-shift-B  extend selection one char forward / back
  172.         alt-shift-F, alt-shift-B    extend selection one word forward / back
  173.         ctrl-shift-N, ctrl-shift-P  extend selection one line down / up
  174.         ctrl-shift-A, ctrl-shift-E  extend selection to beginning / end of line
  175.  
  176.     Scrolling
  177.         ctrl-v, alt-shift-downarrow scroll one page forward
  178.         alt-v, alt-shift-uparrow    scroll one page back
  179.         ctrl-shift-V, alt-shift-V   scroll four lines forward / back
  180.         ctrl-alt-uparrow            scroll to beginning of document
  181.         ctrl-alt-downarrow          scroll to end of document
  182.         ctrl-l                      scroll to selection
  183.  
  184.     Additional scrolling when editing disabled
  185.         space, del                  scroll one page forward / back
  186.         shift-space, shift-del      scroll four lines forward / back
  187.  
  188.     Miscellaneous
  189.         ctrl-t                      transpose characters
  190.         ctrl-o                      insert new line after caret
  191.         ctrl-space                  collapse selection
  192.         ctrl-q                      quote next key
  193.         ctrl-alt-q                  really quote next key
  194.  
  195. (Ctrl-q causes the next character to be handled directly by the
  196. underlying Text object, with no XText-supplied rebinding; for example,
  197. ctrl-q alt-b inserts a sigma.  Ctrl-alt-q goes one step further and
  198. avoids any special handling that Text normally supplies for that key;
  199. for example, ctrl-alt-q downarrow causes a downarrow character to be
  200. inserted (you'll probably want to be in the symbol font), and
  201. ctrl-alt-q return allows you to insert a newline in a text field.)
  202.  
  203. XText Status and Future
  204. -----------------------
  205. This should be thought of as a beta-test version of XText; although it
  206. has no known bugs, it has not been very heavily exercised.  In
  207. particular, I have not yet built it into any non-trivial programs.  I
  208. plan to maintain & use XText, but I also have a job and this isn't it.
  209.  
  210. XText is freeware; you are welcome to use it, modify it, and
  211. distribute it without restriction (although I would appreciate having
  212. my name kept on it).  It is copyrighted by my employer (Xerox), but
  213. only to prevent someone from claiming that it belongs to them.
  214.  
  215. Please do send me bug reports and suggestions, and let me know if you
  216. find it useful.  This is my first experience with objective-C and
  217. Interface Builder, so there is certainly room for improvement.
  218.  
  219. Anyone want to build a replacement for Edit using XText?
  220.  
  221.  
  222. Mike Dixon
  223. Xerox PARC
  224. 3333 Coyote Hill Rd.
  225. Palo Alto, CA 94304
  226. mdixon@parc.xerox.com
  227.